Sourced from clickhouse-connect's releases.

v1.1.1

clickhouse-connect v1.1.1

This patch release fixes a handful of async-client connectivity bugs and a SHOW ROW POLICIES query routing issue. Recommended for all users on 1.1.0, especially those running the async client behind a proxy or against keep-alive-prone pools.

What's Changed

Bug Fixes

• Async client: ping() now routes through the configured proxy, matching _raw_request. Previously the proxy was omitted, so ping() falsely returned False on networks where the server was only reachable via the proxy. Closes #757.
• Fix query("SHOW ROW POLICIES") / query("SHOW POLICIES") by routing these non-tabular statements without appending FORMAT Native. Empty row-policy SHOW results now return "" instead of QuerySummary. Closes #761.
• Async client: retry stale keep-alive resets surfaced by aiohttp as ClientOSError or ClientConnectionResetError, fixing large async inserts on killed pooled connections. Closes #763.
• Async client: do not retry aiohttp timeout, connector, or fingerprint errors — these can indicate the request was already delivered or a config issue, not a stale connection.
• Sync client: also retry stale keep-alive BrokenPipeError (in addition to ConnectionResetError), matching the async behavior.

Installation

pip install clickhouse-connect

Sourced from clickhouse-connect's changelog.

1.1.1, 2026-05-27

Bug Fixes

• Async client: ping() now routes through the configured proxy, matching _raw_request. Previously the proxy was omitted, so ping() falsely returned False on networks where the server was only reachable via the proxy. Closes #757.
• Fix query("SHOW ROW POLICIES")/query("SHOW POLICIES") by routing these non-tabular statements without appending FORMAT Native. Empty row-policy SHOW command results now return "" instead of QuerySummary. Closes #761.
• Async client: retry stale keep-alive resets surfaced by aiohttp as ClientOSError or ClientConnectionResetError, fixing large async inserts on killed pooled connections. Closes #763.
• Async client: do not retry aiohttp timeout, connector, or fingerprint errors as these can indicate the request was already delivered or a config issue, not a stale connection.
• Sync client: also retry stale keep-alive BrokenPipeError (in addition to ConnectionResetError), matching the async behavior.

1.1.0, 2026-05-26

Compatibility

• Async client now requires aiohttp>=3.9.0. This is required to support TLS SNI override via server_host_name, because aiohttp added the per-request server_hostname option in 3.9.
• SQLAlchemy: the alembic extra now requires alembic>=1.16 (previously >=1.9) so the documented IF EXISTS / IF NOT EXISTS Alembic operation kwargs are available.

Bug Fixes

• SQLAlchemy: op.add_column(..., clickhouse_settings={...}) now works through the public Alembic operations API, and rendered AddColumnOp migrations preserve extra ClickHouse kwargs.
• SQLAlchemy: Alembic migrations now handle comments with ClickHouse-compatible syntax. Column comments on CREATE TABLE / ADD COLUMN no longer emit rejected COMMENT ON COLUMN statements; table comments are now emitted in generated DDL, reflected for no-op autogenerate, and changed or dropped with ALTER TABLE ... MODIFY COMMENT.
• Async client: server_host_name now also overrides the TLS SNI / certificate hostname, matching the sync client. Previously the async path only applied it to the HTTP Host header, so connecting to host A while presenting SNI B (the 0.x pool_mgr=urllib3.PoolManager(server_hostname=...) pattern, useful for ClickHouse Cloud VPC endpoints reached via external DNS) was not expressible against the new aiohttp-based client. Both _raw_request and ping() now pass ssl=self._ssl_context, server_hostname=self.server_host_name per request when an SSL context is in use. Closes #752.
• Drain the full retries budget on connection-error retries in _raw_request instead of only retrying once. Previously both the sync and async clients gated network-error retries on attempts == 1, so two consecutive aiohttp.ServerDisconnectedErrors (or ConnectionResetErrors on the sync path) surfaced as OperationalError even when query_retries would have allowed another attempt. Read paths now drain query_retries; insert/command paths still get one retry (retries=0 callers). Sync raw_query and raw_stream (the foundation for query_arrow / query_arrow_stream) now also pass query_retries so they match their async counterparts. Adds a 0.1 * attempts backoff between connection-error retries to match the 429/503/504 branch. Closes #754.
• quote_identifier now re-escapes inputs that start and end with ` or " but contain unescaped inner occurrences of the same quote character, instead of passing them through unchanged. Validly pre-quoted identifiers like backslash or doubled-quote escaping still pass through untouched. Closes #737.
• SQLAlchemy: quote string-valued engine and operation settings as ClickHouse string literals when rendering SETTINGS clauses. Previously settings like MergeTree(settings={"storage_policy": "hot_cold"}) or op.add_column(..., clickhouse_settings={"mutations_sync": "2"}) emitted unquoted SQL (storage_policy = hot_cold), which ClickHouse rejected. Numeric and boolean settings are unchanged.
• SQLAlchemy: preserve engine settings on reflection. build_engine() previously hardcoded engine.settings = {} even when the reflected DDL contained a SETTINGS clause, so callers reading engine.settings after reflection saw an empty dict. settings is now populated from the parsed engine kwargs, decoding ClickHouse string-literal escapes (\\, \', \n, etc.) and preserving float-valued settings as floats — round-trip parity with the construction path.
• SQLAlchemy: Inspector error messages from get_table_metadata() now report the resolved database name i.e. from currentDatabase() when schema was not provided instead of literal None.

1.1.0a2, 2026-05-07

Follow-up alpha to 1.1.0a1 with a fix for an ORM compile-path regression in the new ClickHouse Select modifiers, rebased on 1.0.0rc3 so the insert-retry fix from rc3 is also included.

Bug Fixes

• SQLAlchemy: FINAL, SAMPLE, PREWHERE, and LIMIT BY modifiers are now preserved when a select() is built from ORM-mapped attributes (e.g. select(Event.id)) rather than Core columns. Previously the ORM compile path rebuilt the inner Select via Select._create_raw_select, which dropped the modifier instance attributes, so the compiled SQL silently emitted no modifier. The compiler now falls back to compile_state.select_statement (the original user-built Select) to recover the modifiers. Closes #730.

1.0.1, 2026-05-19

Bug Fixes

• Recognize Fixed/UTC±HH:MM:SS timezones emitted by ClickHouse servers without an IANA tz database (in column types, X-ClickHouse-Timezone, and SELECT timezone()). Previously raised ProgrammingError on any column read, parameter bind, or client init touching one. The exact ±24:00:00 boundary remains rejected because Python's datetime.timezone cannot represent it. Closes #702.
• Async client: drain in-flight requests before closing the underlying aiohttp session. Sharing a single AsyncClient across concurrent coroutines previously raised RuntimeError: Session is closed (and related Connection reset / QUERY_WITH_SAME_ID_IS_ALREADY_RUNNING cascades) whenever max_connection_age triggered a pool rotation while other tasks had requests in flight. close_connections() now installs the new session before retiring the old one, and waits for outstanding requests (including streaming responses) to release their lease before tearing it down. close() clears self._session so post-close calls fail with ProgrammingError instead of leaking aiohttp's RuntimeError. Closes #744
• Async client: ca_cert="certifi" shorthand now resolves to certifi.where(), matching the sync client. Previously the async path passed the literal string to ssl_context.load_verify_locations, producing FileNotFoundError. Closes #742
• Fix SQLAlchemy dialect rendering for ILIKE and NOT ILIKE expressions to use native ClickHouse syntax instead of the generic SQLAlchemy lower(...) LIKE lower(...) fallback.

1.0.0, 2026-05-13

No code changes since 1.0.0rc3. See the 1.0.0rc1, 1.0.0rc2, and 1.0.0rc3 entries below for the full set of changes included in the 1.0.0 release.

Upgrading from a 0.15.x or earlier release? See https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md for a guide to the breaking changes and their replacements.

1.0.0rc3, 2026-05-07

Bug Fixes

• Fix intermittent Code: 62. Empty query. (SYNTAX_ERROR) on inserts when a pooled keep-alive connection is reset between attempts. The retry path now rebuilds the insert body instead of replaying an already-drained generator. Affects both sync and async clients. Closes #731

... (truncated)

• 407691a 1.1.1 release prep (#767)
• 4a26b08 route ping through proxy (#765)
• 30e3ea9 Joe/763 async client does not retry due to miscategorized exceptions (#764)
• bf1aa5b fix show row policy handing (#762)
• 579a48b 1.1.0 release prep (#760)
• 769eac0 simplify alembic wex, col settings & comments fixes (#759)
• 9072576 Integrate Alembic support & SQLAlchemy improvements into main (#758)
• 4bfe64e propagate server_host_name to TLS SNI (#756)
• 31910e0 async client: retry ServerDisconnectedErrors up to retries (#755)
• 2ad7ef3 fix unescaped inner quotes in pre-quoted identifiers (#750)
• Additional commits viewable in compare view